HAL OTFDEC migration: Exported functions

This section provides information about the HAL OTFDEC function migration.

In HAL2,The OTFDEC is managed as a core driver, and its wrapped by the HAL XSPI driver. For more details about the OTFDEC core APIs, please refer to HAL OTFDEC migration: List of applicable concepts.

HAL OTFDEC cipher operation

In HAL1, the HAL_OTFDEC_Cipher is used to generate ciphertext for a designated OTFDEC region. This API operates directly on the OTFDEC peripheral, and interrupts are configured separately through HAL macros.

In HAL2, the HAL_XSPI_OTFDEC_Encrypt is used to encrypt data as part of an XSPI-based external memory flow. This API includes an interrupts parameter, providing the interrupt sources that shall be enabled during the operation.

HAL1

HAL2 

HAL_OTFDEC_Cipher(OTFDEC_HandleTypeDef *hotfdec,
                  uint32_t RegionIndex,
                  const uint32_t *input,
                  uint32_t *output,
                  uint32_t size,
                  uint32_t start_address)

HAL_XSPI_OTFDEC_Encrypt(hal_xspi_handle_t *hxspi,
                        hal_xspi_otfdec_region_t region,
                        uint32_t *p_input,
                        uint32_t *p_output,
                        uint32_t size_byte,
                        uint32_t start_address,
                        uint32_t interrupts)

Usage example

HAL1

HAL2 

#define START_ADRESS_OTFDEC1_REGION1   0x90000000
#define PLAIN_SIZE                     16U
/* Plain data */
uint32_t Plain[PLAIN_SIZE] =
{
  0x00, 0x10, 0x20, 0x30,
  0x40, 0x50, 0x60, 0x70,
  0x80, 0x90, 0xA0, 0xB0,
  0xC0, 0xD0, 0xE0, 0xF0
};
/* Temporary buffer to store ciphered data before copy in external memory */
uint32_t TX_Buffer_Cryp[PLAIN_SIZE]={0};
/* Enable all interrupts of OTFDEC peripheral */
__HAL_OTFDEC_ENABLE_IT(&hotfdec, OTFDEC_ALL_INT);
/* Enable enciphering mode before calling cipher API. */
HAL_OTFDEC_EnableEnciphering(&hotfdec);
HAL_OTFDEC_Cipher(&hotfdec1, OTFDEC_REGION1,
                  Plain,
                  TX_Buffer_Cryp,
                  PLAIN_SIZE,
                  START_ADRESS_OTFDEC1_REGION1);

#define START_ADRESS_OTFDEC1_REGION1   0x90000000
#define PLAIN_SIZE                     16U
/* Plain data */
uint32_t Plain[PLAIN_SIZE] =
{
  0x00, 0x10, 0x20, 0x30,
  0x40, 0x50, 0x60, 0x70,
  0x80, 0x90, 0xA0, 0xB0,
  0xC0, 0xD0, 0xE0, 0xF0
};
/* Temporary buffer to store ciphered data before copy in external memory */
uint32_t TX_Buffer_Cryp[PLAIN_SIZE]={0};

HAL_XSPI_OTFDEC_Encrypt(&hxspi1, HAL_XSPI_OTFDEC_REGION_1,
                        Plain,
                        TX_Buffer_Cryp,
                        PLAIN_SIZE,
                        START_ADRESS_OTFDEC1_REGION1,
                        HAL_XSPI_OTFDEC_IT_ALL);

HAL OTFDEC attributes configuration

HAL1

HAL2 

HAL_OTFDEC_ConfigAttributes(OTFDEC_HandleTypeDef *hotfdec,
                           uint32_t Attributes);

HAL_XSPI_OTFDEC_SetPrivAttr(hal_xspi_t instance,
                            hal_xspi_otfdec_priv_attr_t priv_attr);

Note

For more details, refer to HAL OTFDEC attribute flags constants

HAL OTFDEC enciphering disable

HAL1

HAL2 

HAL_OTFDEC_DisableEnciphering(OTFDEC_HandleTypeDef *hotfdec)

Used internally and does not affect user level operation.

HAL OTFDEC enciphering enable

HAL1

HAL2 

HAL_OTFDEC_EnableEnciphering(OTFDEC_HandleTypeDef *hotfdec)

Used internally and does not affect user level operation.

HAL OTFDEC configuration attributes retrieval

HAL1

HAL2 

HAL_OTFDEC_GetConfigAttributes(OTFDEC_HandleTypeDef *hotfdec, uint32_t *Attributes)

HAL_XSPI_OTFDEC_GetPrivAttr(hal_xspi_t instance)

HAL OTFDEC state retrieval

HAL1

HAL2 

HAL_OTFDEC_GetState(OTFDEC_HandleTypeDef *hotfdec)

/* XSPI OTFDEC region state */
HAL_XSPI_OTFDEC_GetRegionState(const hal_xspi_handle_t *hxspi,
                               hal_xspi_otfdec_region_t region)

HAL OTFDEC key CRC computation

HAL1

HAL2 

HAL_OTFDEC_KeyCRCComputation(uint32_t *pKey)

HAL_OTFDEC_KeyCRCComputation is no longer available in HAL2.

In HAL2, the function HAL_XSPI_OTFDEC_SetConfigRegion() automatically calculates the key CRC value and compares it to the key CRC reported by the OTFDEC peripheral. It reports an error if the CRC does not match (i.e. there is a HW error during key programming).

HAL OTFDEC region configuration

HAL1

HAL2

In HAL1, the region lock configuration is handled directly by HAL_OTFDEC_RegionConfig through the lock parameter. 

HAL_OTFDEC_RegionConfig(OTFDEC_HandleTypeDef *hotfdec,
                        uint32_t RegionIndex,
                        const OTFDEC_RegionConfigTypeDef *Config,
                        uint32_t lock)

In HAL2, the region lock configuration has been separated from the configuration API and is now managed through dedicated unitary HAL functions. 

HAL_XSPI_OTFDEC_SetConfigRegion(hal_xspi_handle_t *hxspi,
                                hal_xspi_otfdec_region_t region,
                                const hal_xspi_otfdec_config_t *p_config,
                                const hal_xspi_otfdec_key_t *p_key_config);

HAL_XSPI_OTFDEC_LockRegionConfig(hal_xspi_handle_t *hxspi,
                                 hal_xspi_otfdec_region_t region)

Note

For more details, refer to HAL OTFDEC region configuration type definition

HAL OTFDEC region disable

HAL1

HAL2 

HAL_OTFDEC_RegionDisable(OTFDEC_HandleTypeDef *hotfdec, uint32_t RegionIndex)

Used internally and does not affect user level operation.

HAL OTFDEC region enable

HAL1

HAL2 

HAL_OTFDEC_RegionEnable(OTFDEC_HandleTypeDef *hotfdec, uint32_t RegionIndex)

Used internally and does not affect user level operation.

HAL OTFDEC region configuration retrieval

HAL1

HAL2 

HAL_OTFDEC_RegionGetConfig(OTFDEC_HandleTypeDef *hotfdec,
                           uint32_t RegionIndex,
                           OTFDEC_RegionConfigTypeDef *Config)

HAL_XSPI_OTFDEC_GetConfigRegion(hal_xspi_handle_t *hxspi,
                                hal_xspi_otfdec_region_t  region,
                                hal_xspi_otfdec_config_t *p_config)

HAL OTFDEC region key CRC retrieval

HAL1

HAL2 

HAL_OTFDEC_RegionGetKeyCRC(OTFDEC_HandleTypeDef *hotfdec, uint32_t RegionIndex)

HAL_XSPI_OTFDEC_GetRegionKeyCRC(const hal_xspi_handle_t *hxspi,
                                             hal_xspi_otfdec_region_t region,
                                             uint8_t *p_key_crc)

HAL OTFDEC region key lock

HAL1

HAL2 

HAL_OTFDEC_RegionKeyLock(OTFDEC_HandleTypeDef *hotfdec, uint32_t RegionIndex)

HAL_XSPI_OTFDEC_LockRegionKey(hal_xspi_handle_t *hxspi, hal_xspi_otfdec_region_t region)

HAL OTFDEC region key setting

HAL1

HAL2 

HAL_OTFDEC_RegionSetKey(OTFDEC_HandleTypeDef *hotfdec, uint32_t RegionIndex, uint32_t *pKey)

Used internally and does not affect user level operation.

The function HAL_OTFDEC_RegionSetKey() has been merged with HAL_XSPI_OTFDEC_SetConfigRegion() to set the region key.

HAL OTFDEC region mode setting

HAL1

HAL2 

HAL_OTFDEC_RegionSetMode(OTFDEC_HandleTypeDef *hotfdec, uint32_t RegionIndex, uint32_t mode)

Used internally and does not affect user level operation.

The function HAL_OTFDEC_RegionSetMode() has been merged with HAL_XSPI_OTFDEC_SetConfigRegion() to set the region mode.